/**
   cl-args.h - Created by Timothy Morey on 3/6/2012.
   
   This file defines an interface by which one can parse simple command line
   arguments supplied to a program.
*/

#ifndef __CL_ARGS_H
#define __CL_ARGS_H

#include "libnvn.h"

#ifdef __cplusplus
extern "C"
{
#endif

/**
  Defines a command line argument, which is a case-sensitive string of 
  alphanumeric characters that may or may not be followed by a corresponding
  value.
*/
typedef struct
{
  char Name[16];          // The long name for the argument.

  char Abbrev;            // A single character abbreviation for the argument.

  int RequiresValue;      // Indicates if the argument requires a value.

  char Description[256];  // A verbose description of the argument.

} ArgDef;

/**
  A CLSchema describes all of the command line  arguments that an application
  may accept.
*/
typedef struct
{
  ArgDef* Args;  // An array of argument definitions.

  int ArgCount;  // The number of argument definitions.

} CLSchema;

/**
  Indicates if the user-supplied command line arguments contain the specified
  argument.
   
  @param[in] argc The argument count, as provided by the argument to main.
  @param[in] argv The array of command line arguments, as provided to main.
  @param[in] arg The argument that we are searching for.
  @param[in] schema The CLSchema that describes the application's arguments.
  @param[out] contains The provided int will be set to 1 if the argument is
  found and 0 otherwise.
   
  @return An nvn error code indicating if the operation was successful.
*/
EXPORT int ContainsArg(int argc, char* argv[], const char* arg, CLSchema* schema, int* contains);

/**
  Gets the value associated with the specified argument.  If no such argument
  can be found, or if it does not have a value, 0 will be returned.
   
  @param[in] argc The argument count, as provided by the argument to main.
  @param[in] argv The array of command line arguments, as provided to main.
  @param[in] arg The argument that we are searching for.
  @param[in] schema The CLSchema that describes the application's arguments.
  @param[out] value The pointer that will be directed to the requested value,
  and it will be set to 0 if the value cannot be found.
   
  @return An nvn error code indicating if the operation was successful.
*/
EXPORT int GetArgValue(int argc, char* argv[], const char* arg, CLSchema* schema, const char** value);

/**
  Prints a description of the CLSchema to standard output, listing each 
  argument along with its description.
   
  @param[in] argc The argument count, as provided by the argument to main.
  @param[in] argv The array of command line arguments, as provided to main.
  @param[in] schema The CLSchema that will be printed to standard output.
   
  @return An nvn error code indicating if the operation was successful.
*/
EXPORT int PrintArgSchema(int argc, char* argv[], CLSchema* schema);

/**
  Determines if the supplied command line arguments are valid for the given
  schema.  If they are not, messages will be written to the standard error
  stream that describe how the arguments are invalid.
   
  @param[in] argc The argument count, as provided by the argument to main.
  @param[in] argv The array of command line arguments, as provided to main.
  @param[in] schema The CLSchema that describes the correct format for the args.
  @param[out] valid The provided int will be set to 1 if the arguments match
  the schema and 0 otherwise.
   
  @return An nvn error code indicating if the operation was successful.
*/
EXPORT int ValidateArgs(int argc, char* argv[], CLSchema* schema, int* valid);

#ifdef __cplusplus
}
#endif

#endif
